package com.zenithmind.document.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.document.pojo.domain.DocumentTag;
import com.zenithmind.document.pojo.dto.DocumentTagCreateDTO;
import com.zenithmind.document.pojo.dto.DocumentTagUpdateDTO;
import com.zenithmind.document.pojo.query.DocumentTagQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentTagVO;

import java.util.List;

/**
 * 文档标签服务接口
 * 遵循接口隔离原则：专注于标签管理功能
 * 遵循单一职责原则：只负责标签相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentTagService extends IService<DocumentTag> {

    /**
     * 创建标签
     * 
     * @param createDTO 标签信息
     * @return 标签记录
     */
    DocumentTagVO createTag(DocumentTagCreateDTO createDTO);

    /**
     * 更新标签
     * 
     * @param id 标签ID
     * @param updateDTO 更新信息
     * @return 是否成功
     */
    Boolean updateTag(String id, DocumentTagUpdateDTO updateDTO);

    /**
     * 删除标签
     * 
     * @param id 标签ID
     * @return 是否成功
     */
    Boolean deleteTag(String id);

    /**
     * 批量删除标签
     * 
     * @param ids 标签ID列表
     * @return 是否成功
     */
    Boolean batchDeleteTags(List<String> ids);

    /**
     * 分页查询标签
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentTagVO> getTagPage(DocumentTagQueryDTO queryDTO);

    /**
     * 获取标签详情
     * 
     * @param id 标签ID
     * @return 标签详情
     */
    DocumentTagVO getTagDetail(String id);

    /**
     * 根据名称获取标签
     * 
     * @param name 标签名称
     * @return 标签信息
     */
    DocumentTagVO getTagByName(String name);

    /**
     * 获取所有标签
     * 
     * @return 标签列表
     */
    List<DocumentTagVO> getAllTags();

    /**
     * 搜索标签
     * 
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> searchTags(String keyword, Integer limit);

    /**
     * 获取热门标签
     * 
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> getHotTags(Integer limit);

    /**
     * 获取最新标签
     * 
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> getLatestTags(Integer limit);

    /**
     * 获取用户标签
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> getUserTags(String userId, Integer limit);

    /**
     * 获取文档标签
     * 
     * @param documentId 文档ID
     * @return 标签列表
     */
    List<DocumentTagVO> getDocumentTags(String documentId);

    /**
     * 为文档添加标签
     * 
     * @param documentId 文档ID
     * @param tagNames 标签名称列表
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean addTagsToDocument(String documentId, List<String> tagNames, String userId);

    /**
     * 从文档移除标签
     * 
     * @param documentId 文档ID
     * @param tagNames 标签名称列表
     * @return 是否成功
     */
    Boolean removeTagsFromDocument(String documentId, List<String> tagNames);

    /**
     * 替换文档标签
     * 
     * @param documentId 文档ID
     * @param tagNames 新标签名称列表
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean replaceDocumentTags(String documentId, List<String> tagNames, String userId);

    /**
     * 批量为文档添加标签
     * 
     * @param documentIds 文档ID列表
     * @param tagNames 标签名称列表
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean batchAddTagsToDocuments(List<String> documentIds, List<String> tagNames, String userId);

    /**
     * 批量从文档移除标签
     * 
     * @param documentIds 文档ID列表
     * @param tagNames 标签名称列表
     * @return 是否成功
     */
    Boolean batchRemoveTagsFromDocuments(List<String> documentIds, List<String> tagNames);

    /**
     * 获取标签使用统计
     * 
     * @param tagId 标签ID
     * @return 统计信息
     */
    Object getTagUsageStatistics(String tagId);

    /**
     * 获取标签云数据
     * 
     * @param limit 限制数量
     * @return 标签云数据
     */
    List<Object> getTagCloudData(Integer limit);

    /**
     * 获取相关标签
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 相关标签列表
     */
    List<DocumentTagVO> getRelatedTags(String tagId, Integer limit);

    /**
     * 合并标签
     * 
     * @param sourceTagId 源标签ID
     * @param targetTagId 目标标签ID
     * @return 是否成功
     */
    Boolean mergeTags(String sourceTagId, String targetTagId);

    /**
     * 拆分标签
     * 
     * @param tagId 标签ID
     * @param newTagNames 新标签名称列表
     * @return 是否成功
     */
    Boolean splitTag(String tagId, List<String> newTagNames);

    /**
     * 重命名标签
     * 
     * @param tagId 标签ID
     * @param newName 新名称
     * @return 是否成功
     */
    Boolean renameTag(String tagId, String newName);

    /**
     * 检查标签是否存在
     * 
     * @param name 标签名称
     * @return 是否存在
     */
    Boolean checkTagExists(String name);

    /**
     * 创建或获取标签
     * 
     * @param name 标签名称
     * @param userId 用户ID
     * @return 标签信息
     */
    DocumentTagVO createOrGetTag(String name, String userId);

    /**
     * 批量创建或获取标签
     * 
     * @param names 标签名称列表
     * @param userId 用户ID
     * @return 标签列表
     */
    List<DocumentTagVO> batchCreateOrGetTags(List<String> names, String userId);

    /**
     * 获取标签建议
     * 
     * @param input 输入文本
     * @param limit 限制数量
     * @return 建议标签列表
     */
    List<String> getTagSuggestions(String input, Integer limit);

    /**
     * 自动提取标签
     * 
     * @param content 文档内容
     * @param limit 限制数量
     * @return 提取的标签列表
     */
    List<String> extractTagsFromContent(String content, Integer limit);

    /**
     * 获取标签趋势
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 趋势数据
     */
    List<Object> getTagTrends(Integer days, Integer limit);

    /**
     * 获取标签分类
     * 
     * @return 标签分类
     */
    List<Object> getTagCategories();

    /**
     * 设置标签分类
     * 
     * @param tagId 标签ID
     * @param categoryId 分类ID
     * @return 是否成功
     */
    Boolean setTagCategory(String tagId, String categoryId);

    /**
     * 获取分类下的标签
     * 
     * @param categoryId 分类ID
     * @param limit 限制数量
     * @return 标签列表
     */
    List<DocumentTagVO> getTagsByCategory(String categoryId, Integer limit);

    /**
     * 导出标签数据
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    Object exportTags(DocumentTagQueryDTO queryDTO);

    /**
     * 导入标签数据
     * 
     * @param tags 标签数据
     * @return 导入数量
     */
    Integer importTags(List<DocumentTagCreateDTO> tags);

    /**
     * 清理未使用的标签
     * 
     * @return 清理数量
     */
    Integer cleanupUnusedTags();

    /**
     * 同步标签统计
     * 
     * @return 是否成功
     */
    Boolean syncTagStatistics();

    /**
     * 获取标签使用历史
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 使用历史
     */
    List<Object> getTagUsageHistory(String tagId, Integer limit);

    /**
     * 推荐标签给用户
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 推荐标签列表
     */
    List<DocumentTagVO> recommendTagsToUser(String userId, Integer limit);

    /**
     * 获取标签共现分析
     * 
     * @param tagId 标签ID
     * @param limit 限制数量
     * @return 共现分析数据
     */
    List<Object> getTagCooccurrenceAnalysis(String tagId, Integer limit);
}
